Closes #608

Stacked on #669 — merge that first. The registry is where scopes are stored, so this branch is based on it. Until #669 lands the diff below also shows agents.py / test_agents.py; it shrinks to scopes.py, trust.py, jsonl_server.py, http_server.py, capabilities.py, models.py and test_scopes.py the moment it does.

a bearer token was all-or-nothing: hold it and you could call all 73 kb.* methods, kb.approve included. fine for a solo human, wrong for a CI job that should only read or a triage bot that should only propose. the config-level trusted-agent flag can only widen the gate — this is the first thing in vouch that can narrow it.

withholding kb:approve by default is the review gate, expressed as a credential.

$ vouch agents register ci-bot --subject 29e74dc6 --scope kb:read --scope kb:propose

# that credential, over http:
kb.search        -> ok
kb.propose_claim -> ok
kb.approve       -> permission_denied: kb.approve requires kb:approve;
                    this credential holds kb:read, kb:propose

four coarse scopes, not a per-method allowlist

kb:read / kb:propose / kb:approve / kb:admin. a per-method grammar is more flexible and makes every new kb.* method a config migration for every deployment; four buckets keep that cost at zero.

the two rules that make this safe to ship

an unscoped credential means all scopes. every token issued before this keeps working exactly as it did. an empty scope set is unrestricted, never denied — the opposite choice breaks every deployment on upgrade. test_unscoped_permits_everything walks all 73 methods.

every method must be classified. METHOD_SCOPES is exhaustive over capabilities.METHODS, enforced both ways: test_every_method_is_classified catches a new method with no scope, and test_the_table_has_no_entries_for_methods_that_do_not_exist catches a stale entry. an unclassified method is denied to a scoped caller — fails closed, because a deny-list in a trust-centric system fails open.

one implementation, three surfaces

enforcement is trust.require_scope, called from the two dispatch points that already exist: handle_request for JSONL/HTTP and wrap_tool_fn for MCP. the check runs before the handler, so a refused call cannot have side effects on its way to being refused — test_denial_happens_before_the_handler_runs spies on the handler and asserts it never ran.

a couple of details worth checking:

• a wrong token never reaches the scope check, so it cannot probe the table.
• an unknown method still reports method_not_found, not permission_denied — scoping must not turn a typo into a permissions puzzle.
• _meta.vouch_trust only grows a scopes key when the credential is actually scoped, so unscoped callers see the byte-identical block they saw before.

discovery, not trial and error

kb.capabilities reports the caller's effective scopes and the exact method list they may call, so an agent finds out what it may do up front instead of failing method by method.

note on the VEP question

the issue says this "probably wants a VEP" as a surface change. i think the additive shape avoids needing one — kb.capabilities gains a field, _meta.vouch_trust gains an optional key, and unscoped behaviour is unchanged — but that is your call, and i would rather raise it than assume. happy to write one if you want the surface change recorded.

scope enforcement is here; #609's per-KB credential binding is not, and scopes stays plain recorded metadata on the registry row for anything else to build on.

tests

46 cases in tests/test_scopes.py: the exhaustiveness guards, representative methods per bucket, permits including the unscoped and unclassified paths, parse_scopes normalisation and its refusal of a typo'd scope, enforcement across all three credential shapes on the JSONL dispatch, the sync and async MCP wrappers, the trust block, kb.capabilities, and the MCP-over-HTTP ASGI middleware resolving registry scopes onto the request.

verification

pytest tests/ -q --ignore=tests/embeddings   green
mypy src                                     Success: no issues found in 121 source files
ruff check src tests                         All checks passed!
diff-cover --fail-under 100                  100%